/**
 * @file protocol_sequence.h
 * @brief 104协议序列号管理头文件
 * @details 本文件定义了104协议的序列号管理功能，包括发送序列号、接收序列号
 *          管理、序列号验证、序列号回绕处理等。实现完整的104协议序列号控制逻辑。
 * 
 *          主要功能包括：
 *          - 序列号生成：管理发送序列号的生成和递增
 *          - 序列号验证：验证接收序列号的有效性
 *          - 序列号确认：处理发送和接收序列号的确认
 *          - 窗口管理：管理接收窗口和未确认序列号
 *          - 重复检测：检测和处理重复序列号
 *          - 乱序处理：处理乱序到达的序列号
 *          - 回绕处理：处理序列号回绕情况
 *          - 统计信息：记录序列号相关的统计数据
 *          - 回调机制：支持错误和回绕事件通知
 * 
 * @author zyb
 * @date 2025-10-15
 * @version 1.0
 * 
 * @note 本模块是104协议栈的核心组件，负责管理协议序列号的生命周期
 * @warning 所有函数都是线程安全的，使用互斥锁保护共享数据
 * @see protocol_sequence.c
 * @see protocol_types.h
 * @see error_codes.h
 */

#ifndef PROTOCOL_SEQUENCE_H
#define PROTOCOL_SEQUENCE_H

#include "../../common/types/include/protocol_types.h"
#include "../../common/error/include/error_codes.h"
#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 序列号类型定义 ==================== */

/**
 * @brief 序列号方向枚举
 * @details 定义了序列号的方向类型，用于区分发送和接收序列号的处理。
 *          在104协议中，发送和接收序列号需要分别管理。
 */
typedef enum {
    SEQUENCE_DIRECTION_SEND = 0,       /* 发送序列号：用于发送数据的序列号 */
    SEQUENCE_DIRECTION_RECEIVE         /* 接收序列号：用于接收数据的序列号 */
} sequence_direction_t;

/**
 * @brief 序列号状态枚举
 * @details 定义了序列号验证和处理的各种状态，用于标识序列号的有效性
 *          和处理结果。这些状态用于序列号验证和错误处理。
 */
typedef enum {
    SEQUENCE_STATE_VALID = 0,          /* 有效状态：序列号有效，可以正常处理 */
    SEQUENCE_STATE_INVALID,            /* 无效状态：序列号超出有效范围 */
    SEQUENCE_STATE_DUPLICATE,          /* 重复状态：序列号重复，已经接收过 */
    SEQUENCE_STATE_OUT_OF_ORDER,       /* 乱序状态：序列号不在接收窗口内 */
    SEQUENCE_STATE_OVERFLOW            /* 溢出状态：序列号溢出或窗口已满 */
} sequence_state_t;

/* ==================== 序列号配置 ==================== */

/**
 * @brief 序列号配置结构体
 * @details 定义了序列号管理器的配置参数，包括最大序列号、窗口大小、
 *          重试策略、检测功能等。所有配置参数会影响序列号管理器的
 *          行为特征和性能表现。
 */
typedef struct {
    uint16_t max_sequence_number;      /* 最大序列号：序列号的最大值，超过此值会回绕 */
    uint16_t window_size;              /* 窗口大小：接收窗口的大小，用于乱序检测 */
    uint16_t max_unacknowledged;       /* 最大未确认数：允许的最大未确认序列号数量 */
    bool enable_duplicate_detection;   /* 启用重复检测：是否启用重复序列号检测功能 */
    bool enable_out_of_order_detection; /* 启用乱序检测：是否启用乱序序列号检测功能 */
} protocol_sequence_config_t;

/* ==================== 序列号统计 ==================== */

/**
 * @brief 序列号统计信息结构体
 * @details 记录了序列号管理器的运行统计信息，包括各种操作的计数、
 *          错误统计、回绕次数等。统计信息用于监控序列号状态、性能分析
 *          和故障诊断。所有计数器都是累积值，可以通过重置函数清零。
 */
typedef struct {
    uint64_t total_sent;               /* 总发送数：发送的序列号总数 */
    uint64_t total_received;           /* 总接收数：接收的序列号总数 */
    uint64_t duplicates_detected;      /* 检测到的重复数：检测到的重复序列号总数 */
    uint64_t out_of_order_detected;    /* 检测到的乱序数：检测到的乱序序列号总数 */
    uint64_t invalid_sequences;        /* 无效序列号数：无效序列号的总数 */
    uint64_t sequence_wraps;           /* 序列号回绕次数：序列号回绕的总次数 */
    uint32_t current_send_seq;         /* 当前发送序列号：下一个要发送的序列号 */
    uint32_t current_receive_seq;      /* 当前接收序列号：已确认接收的最大序列号 */
    uint32_t unacknowledged_count;     /* 未确认数量：当前未确认的序列号个数 */
} protocol_sequence_stats_t;

/* ==================== 序列号句柄 ==================== */

/**
 * @brief 协议序列号管理器句柄
 */
typedef struct protocol_sequence_manager* protocol_sequence_handle_t;

/* ==================== 回调函数类型 ==================== */

/**
 * @brief 序列号错误回调函数类型
 * @details 当序列号错误发生时调用的回调函数。应用程序可以注册此回调
 *          来接收错误通知，实现自定义的错误处理逻辑。
 * 
 * @param direction 序列号方向（发送或接收）
 * @param sequence_number 出错的序列号
 * @param state 错误状态类型
 * @param user_data 用户数据指针
 */
typedef void (*protocol_sequence_error_callback_t)(sequence_direction_t direction, 
                                                  uint16_t sequence_number, 
                                                  sequence_state_t state, 
                                                  void* user_data);

/**
 * @brief 序列号回绕回调函数类型
 * @details 当序列号回绕发生时调用的回调函数。应用程序可以注册此回调
 *          来接收回绕通知，实现自定义的回绕处理逻辑。
 * 
 * @param direction 序列号方向（发送或接收）
 * @param old_sequence 回绕前的序列号
 * @param new_sequence 回绕后的序列号
 * @param user_data 用户数据指针
 */
typedef void (*protocol_sequence_wrap_callback_t)(sequence_direction_t direction, 
                                                 uint16_t old_sequence, 
                                                 uint16_t new_sequence, 
                                                 void* user_data);

/* ==================== 序列号管理函数 ==================== */

/**
 * @brief 创建序列号管理器
 * @details 创建并初始化一个新的104协议序列号管理器实例。该函数会分配内存、
 *          验证配置参数、初始化内部状态和互斥锁，并设置初始的序列号状态。
 *          序列号管理器负责处理发送序列号生成、接收序列号验证、窗口管理等功能。
 * 
 * @param config 序列号配置参数指针，不能为NULL
 * 
 * @return 序列号管理器句柄，成功返回有效句柄，失败返回NULL
 * 
 * @note 创建的序列号管理器需要调用protocol_sequence_destroy()释放资源
 * @warning 配置参数必须通过protocol_sequence_validate_config()验证
 * @see protocol_sequence_destroy
 * @see protocol_sequence_validate_config
 */
protocol_sequence_handle_t protocol_sequence_create(const protocol_sequence_config_t* config);

/**
 * @brief 销毁序列号管理器
 * @details 销毁序列号管理器实例，清理所有相关资源。该函数会先销毁互斥锁，
 *          然后释放内存。这是protocol_sequence_create()的配对函数，用于释放
 *          序列号管理器占用的所有资源。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 销毁成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 调用此函数后，序列号管理器句柄将变为无效，不应再使用
 * @warning 此函数会清理所有序列号状态，请确保在合适的时机调用
 * @see protocol_sequence_create
 */
protocol_error_t protocol_sequence_destroy(protocol_sequence_handle_t handle);

/**
 * @brief 获取下一个发送序列号
 * @details 获取下一个可用的发送序列号。该函数会检查未确认序列号数量是否超过限制，
 *          如果未超过限制，则分配下一个序列号并添加到未确认列表中。如果序列号
 *          超过最大值，会自动进行回绕处理。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param sequence_number 序列号输出缓冲区，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 获取成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 *         - PROTOCOL_ERROR_BUFFER_OVERFLOW: 序列号窗口已满
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 序列号会自动递增，超过最大值时会回绕到0
 * @warning 如果未确认序列号数量达到最大值，将无法获取新的序列号
 * @see protocol_sequence_acknowledge_send
 * @see protocol_sequence_can_send
 */
protocol_error_t protocol_sequence_get_next_send(protocol_sequence_handle_t handle, 
                                                uint16_t* sequence_number);

/**
 * @brief 验证接收序列号
 * @details 验证接收到的序列号是否有效。该函数会检查序列号是否在有效范围内、
 *          是否在接收窗口内、是否为重复序列号等。验证结果用于决定是否接受
 *          该序列号的数据。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param sequence_number 要验证的序列号
 * 
 * @return 序列号状态
 *         - SEQUENCE_STATE_VALID: 序列号有效
 *         - SEQUENCE_STATE_INVALID: 序列号无效（超出范围）
 *         - SEQUENCE_STATE_OUT_OF_ORDER: 序列号乱序（不在窗口内）
 *         - SEQUENCE_STATE_DUPLICATE: 序列号重复
 *         - SEQUENCE_STATE_OVERFLOW: 序列号溢出
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 验证结果会影响统计信息的更新
 * @warning 如果句柄为NULL，返回SEQUENCE_STATE_INVALID
 * @see protocol_sequence_acknowledge_receive
 * @see protocol_sequence_is_in_window
 */
sequence_state_t protocol_sequence_validate_receive(protocol_sequence_handle_t handle, 
                                                   uint16_t sequence_number);

/**
 * @brief 确认接收序列号
 * @details 确认接收到的序列号，更新接收状态和窗口管理。该函数会验证序列号的有效性，
 *          标记序列号为已接收，更新期望接收序列号，并移动接收窗口。如果序列号是连续的，
 *          会自动更新窗口位置。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param sequence_number 要确认的序列号
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 确认成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 序列号无效
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 只有有效的序列号才能被确认
 * @warning 确认序列号会影响接收窗口的位置
 * @see protocol_sequence_validate_receive
 * @see protocol_sequence_get_current_receive
 */
protocol_error_t protocol_sequence_acknowledge_receive(protocol_sequence_handle_t handle, 
                                                      uint16_t sequence_number);

/**
 * @brief 确认发送序列号
 * @details 确认发送的序列号已被接收，更新发送状态。该函数会从未确认列表中
 *          查找并移除指定的序列号，表示该序列号的数据已被对方确认接收。
 *          该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param sequence_number 要确认的序列号
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 确认成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 序列号未找到
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 只有未确认列表中的序列号才能被确认
 * @warning 确认序列号会减少未确认数量，可能允许发送新的序列号
 * @see protocol_sequence_get_next_send
 * @see protocol_sequence_get_unacknowledged_count
 */
protocol_error_t protocol_sequence_acknowledge_send(protocol_sequence_handle_t handle, 
                                                   uint16_t sequence_number);

/**
 * @brief 重置序列号管理器
 * @details 重置序列号管理器到初始状态，清空所有序列号状态和窗口信息。
 *          该函数会将发送序列号、接收序列号、未确认列表、接收窗口等
 *          所有状态重置为初始值。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 重置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 重置后所有序列号状态都将回到初始状态
 * @warning 重置操作不可逆，请谨慎使用
 * @see protocol_sequence_create
 * @see protocol_sequence_get_current_send
 * @see protocol_sequence_get_current_receive
 */
protocol_error_t protocol_sequence_reset(protocol_sequence_handle_t handle);

/* ==================== 序列号查询函数 ==================== */

/**
 * @brief 获取当前发送序列号
 * @details 获取当前序列号管理器的发送序列号。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 当前发送序列号
 *         - 如果句柄为NULL，返回0
 *         - 否则返回当前发送序列号
 * 
 * @note 该函数是线程安全的
 * @see protocol_sequence_get_next_send
 * @see protocol_sequence_get_current_receive
 */
uint16_t protocol_sequence_get_current_send(protocol_sequence_handle_t handle);

/**
 * @brief 获取当前接收序列号
 * @details 获取当前序列号管理器的接收序列号。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 当前接收序列号
 *         - 如果句柄为NULL，返回0
 *         - 否则返回当前接收序列号
 * 
 * @note 该函数是线程安全的
 * @see protocol_sequence_acknowledge_receive
 * @see protocol_sequence_get_current_send
 */
uint16_t protocol_sequence_get_current_receive(protocol_sequence_handle_t handle);

/**
 * @brief 获取未确认的发送序列号数量
 * @details 获取当前未确认的发送序列号数量。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 未确认的发送序列号数量
 *         - 如果句柄为NULL，返回0
 *         - 否则返回未确认数量
 * 
 * @note 该函数是线程安全的
 * @see protocol_sequence_get_next_send
 * @see protocol_sequence_acknowledge_send
 * @see protocol_sequence_can_send
 */
uint32_t protocol_sequence_get_unacknowledged_count(protocol_sequence_handle_t handle);

/**
 * @brief 检查是否可以发送
 * @details 检查是否可以发送新的序列号。该函数会比较当前未确认的序列号数量
 *          与最大未确认数量，判断是否还有发送窗口可用。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 是否可以发送
 *         - true: 可以发送（未确认数量未达到最大值）
 *         - false: 不能发送（未确认数量已达到最大值或句柄为NULL）
 * 
 * @note 该函数是线程安全的
 * @see protocol_sequence_get_next_send
 * @see protocol_sequence_get_unacknowledged_count
 */
bool protocol_sequence_can_send(protocol_sequence_handle_t handle);

/**
 * @brief 获取序列号统计信息
 * @details 获取序列号管理器的统计信息，包括各种操作的计数和状态。
 *          该函数会复制当前的统计信息到提供的缓冲区中，应用程序可以查看
 *          序列号管理器的运行状态。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param stats 统计信息输出缓冲区，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 获取成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 获取的统计信息是当前时刻的快照
 * @see protocol_sequence_stats_t
 */
protocol_error_t protocol_sequence_get_stats(protocol_sequence_handle_t handle, 
                                           protocol_sequence_stats_t* stats);

/* ==================== 回调设置函数 ==================== */

/**
 * @brief 设置序列号错误回调函数
 * @details 设置序列号错误发生时的回调函数。当序列号管理器检测到错误
 *          （如重复序列号、乱序序列号、无效序列号等）时，系统会自动
 *          调用此回调函数通知应用程序。应用程序可以在此函数中处理各种
 *          序列号错误，实现自定义的错误处理逻辑。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param callback 错误处理回调函数指针，可以为NULL（表示取消回调）
 * @param user_data 用户数据指针，会传递给回调函数，可以为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 如果callback为NULL，则取消错误回调
 * @warning 回调函数应该尽快返回，避免阻塞序列号管理器
 * @see protocol_sequence_error_callback_t
 * @see protocol_sequence_set_wrap_callback
 */
protocol_error_t protocol_sequence_set_error_callback(protocol_sequence_handle_t handle, 
                                                     protocol_sequence_error_callback_t callback, 
                                                     void* user_data);

/**
 * @brief 设置序列号回绕回调函数
 * @details 设置序列号回绕发生时的回调函数。当序列号超过最大值发生回绕时，
 *          系统会自动调用此回调函数通知应用程序。应用程序可以在此函数中
 *          处理序列号回绕事件，实现自定义的回绕处理逻辑。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param callback 回绕处理回调函数指针，可以为NULL（表示取消回调）
 * @param user_data 用户数据指针，会传递给回调函数，可以为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 如果callback为NULL，则取消回绕回调
 * @warning 回调函数应该尽快返回，避免阻塞序列号管理器
 * @see protocol_sequence_wrap_callback_t
 * @see protocol_sequence_set_error_callback
 */
protocol_error_t protocol_sequence_set_wrap_callback(protocol_sequence_handle_t handle, 
                                                    protocol_sequence_wrap_callback_t callback, 
                                                    void* user_data);

/* ==================== 配置管理函数 ==================== */

/**
 * @brief 更新序列号配置参数
 * @details 更新序列号管理器的配置参数，包括最大序列号、窗口大小、重试策略等。
 *          该函数会验证新配置的有效性，只有通过验证的配置才会被应用。
 *          配置更新是原子操作，使用互斥锁保护，确保配置的一致性。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param config 新的序列号配置参数，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 更新成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 配置参数无效
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 配置更新会立即生效，影响后续的序列号操作
 * @warning 配置更新不会影响当前正在进行的序列号操作
 * @see protocol_sequence_config_t
 * @see protocol_sequence_validate_config
 * @see protocol_sequence_get_config
 */
protocol_error_t protocol_sequence_update_config(protocol_sequence_handle_t handle, 
                                                const protocol_sequence_config_t* config);

/**
 * @brief 获取序列号配置参数
 * @details 获取序列号管理器的当前配置参数，包括最大序列号、窗口大小、重试策略等。
 *          该函数会复制当前的配置参数到提供的缓冲区中，应用程序可以查看
 *          当前的配置设置。配置获取是原子操作，使用互斥锁保护，确保数据的一致性。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param config 配置参数输出缓冲区，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 获取成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 获取的配置是当前生效的配置参数
 * @see protocol_sequence_config_t
 * @see protocol_sequence_update_config
 * @see protocol_sequence_validate_config
 */
protocol_error_t protocol_sequence_get_config(protocol_sequence_handle_t handle, 
                                            protocol_sequence_config_t* config);

/* ==================== 辅助函数 ==================== */

/**
 * @brief 获取序列号方向名称字符串
 * @details 将序列号方向枚举值转换为对应的字符串名称，用于日志记录和调试。
 *          该函数返回静态字符串数组中的对应项，返回的字符串指针在程序
 *          运行期间保持有效，不需要释放内存。
 * 
 * @param direction 序列号方向枚举值
 * 
 * @return 方向名称字符串
 *         - "SEND": 发送方向
 *         - "RECEIVE": 接收方向
 *         - "UNKNOWN": 未知方向（当direction值无效时）
 * 
 * @note 返回的字符串指针是静态的，不需要释放内存
 * @note 该函数是线程安全的，只读取静态数据
 * @see sequence_direction_t
 * @see protocol_sequence_get_state_name
 */
const char* protocol_sequence_get_direction_name(sequence_direction_t direction);

/**
 * @brief 获取序列号状态名称字符串
 * @details 将序列号状态枚举值转换为对应的字符串名称，用于日志记录和调试。
 *          该函数返回静态字符串数组中的对应项，返回的字符串指针在程序
 *          运行期间保持有效，不需要释放内存。
 * 
 * @param state 序列号状态枚举值
 * 
 * @return 状态名称字符串
 *         - "VALID": 有效状态
 *         - "INVALID": 无效状态
 *         - "DUPLICATE": 重复状态
 *         - "OUT_OF_ORDER": 乱序状态
 *         - "OVERFLOW": 溢出状态
 *         - "UNKNOWN": 未知状态（当state值无效时）
 * 
 * @note 返回的字符串指针是静态的，不需要释放内存
 * @note 该函数是线程安全的，只读取静态数据
 * @see sequence_state_t
 * @see protocol_sequence_get_direction_name
 */
const char* protocol_sequence_get_state_name(sequence_state_t state);

/**
 * @brief 验证序列号配置参数的有效性
 * @details 验证序列号配置参数是否符合104协议的要求和系统限制。
 *          该函数会检查所有必要的配置参数，确保它们的值在有效范围内。
 *          验证包括最大序列号、窗口大小、最大未确认数量等关键参数的合理性检查。
 * 
 * @param config 待验证的序列号配置参数，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 配置验证通过
 *         - PROTOCOL_ERROR_NULL_POINTER: 配置参数为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 配置参数无效
 * 
 * @note 该函数是线程安全的，只读取配置数据
 * @note 验证规则：
 *       - 最大序列号必须大于0
 *       - 窗口大小必须大于0且不超过16
 *       - 最大未确认数量必须大于0且不超过16
 * @see protocol_sequence_config_t
 * @see protocol_sequence_update_config
 * @see protocol_sequence_get_config
 */
protocol_error_t protocol_sequence_validate_config(const protocol_sequence_config_t* config);

/**
 * @brief 计算序列号差值
 * @details 计算两个序列号之间的差值，考虑序列号回绕情况。该函数会处理
 *          序列号超过最大值时的回绕情况，确保差值的计算结果是正确的。
 *          正值表示seq1大于seq2，负值表示seq1小于seq2。
 * 
 * @param seq1 序列号1
 * @param seq2 序列号2
 * @param max_seq 最大序列号
 * 
 * @return 序列号差值
 *         - 正值：seq1 > seq2
 *         - 负值：seq1 < seq2
 *         - 0：seq1 == seq2
 * 
 * @note 该函数是线程安全的，只进行数学计算
 * @note 函数会自动处理序列号回绕情况
 * @see protocol_sequence_is_in_window
 */
int32_t protocol_sequence_calculate_difference(uint16_t seq1, uint16_t seq2, uint16_t max_seq);

/**
 * @brief 检查序列号是否在窗口内
 * @details 检查序列号是否在指定的接收窗口内。该函数会计算序列号与窗口起始位置
 *          的差值，判断是否在窗口大小范围内。函数会自动处理序列号回绕情况。
 * 
 * @param sequence_number 要检查的序列号
 * @param window_start 窗口起始序列号
 * @param window_size 窗口大小
 * @param max_seq 最大序列号
 * 
 * @return 是否在窗口内
 *         - true: 序列号在窗口内
 *         - false: 序列号不在窗口内
 * 
 * @note 该函数是线程安全的，只进行数学计算
 * @note 函数会自动处理序列号回绕情况
 * @see protocol_sequence_calculate_difference
 * @see protocol_sequence_validate_receive
 */
bool protocol_sequence_is_in_window(uint16_t sequence_number, 
                                   uint16_t window_start, 
                                   uint16_t window_size, 
                                   uint16_t max_seq);

#ifdef __cplusplus
}
#endif

#endif /* PROTOCOL_SEQUENCE_H */
